<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en-US">
<head>
<!-- GenHTML revision 25226-->
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<title>Creating Custom Component Classes - The Java EE 6 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2011-03-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/javaeetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td width="400px"><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnaph.html">4.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="giepx.html">5.&nbsp;&nbsp;Introduction to Facelets</a></p>
<p class="toc level2"><a href="gjddd.html">6.&nbsp;&nbsp;Expression Language</a></p>
<p class="toc level2"><a href="bnaqz.html">7.&nbsp;&nbsp;Using JavaServer Faces Technology in Web Pages</a></p>
<p class="toc level2"><a href="gjcut.html">8.&nbsp;&nbsp;Using Converters, Listeners, and Validators</a></p>
<p class="toc level2"><a href="bnatx.html">9.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkmaa.html">10.&nbsp;&nbsp;JavaServer Faces Technology Advanced Concepts</a></p>
<p class="toc level2"><a href="bnawo.html">11.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="gkiow.html">12.&nbsp;&nbsp;Using Ajax with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkhxa.html">13.&nbsp;&nbsp;Advanced Composite Components</a></p>
<p class="toc level2"><a href="bnavg.html">14.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level3"><a href="bnavh.html">Determining Whether You Need a Custom Component or Renderer</a></p>
<p class="toc level4"><a href="bnavh.html#bnavi">When to Use a Custom Component</a></p>
<p class="toc level4"><a href="bnavh.html#bnavj">When to Use a Custom Renderer</a></p>
<p class="toc level4"><a href="bnavh.html#bnavk">Component, Renderer, and Tag Combinations</a></p>
<p class="toc level3 tocsp"><a href="bnavt.html">Steps for Creating a Custom Component</a></p>
<div id="scrolltoc" class="onpage">
<p class="toc level3"><a href="">Creating Custom Component Classes</a></p>
<p class="toc level4"><a href="#bnavv">Specifying the Component Family</a></p>
<p class="toc level4"><a href="#bnavw">Performing Encoding</a></p>
<p class="toc level4"><a href="#bnavx">Performing Decoding</a></p>
<p class="toc level4"><a href="#bnavy">Enabling Component Properties to Accept Expressions</a></p>
<p class="toc level4"><a href="#bnavz">Saving and Restoring State</a></p>
</div>
<p class="toc level3 tocsp"><a href="bnawa.html">Delegating Rendering to a Renderer</a></p>
<p class="toc level4"><a href="bnawa.html#bnawb">Creating the Renderer Class</a></p>
<p class="toc level4"><a href="bnawa.html#bnawc">Identifying the Renderer Type</a></p>
<p class="toc level3 tocsp"><a href="bnawd.html">Handling Events for Custom Components</a></p>
<p class="toc level3"><a href="bnawe.html">Creating the Component Tag Handler</a></p>
<p class="toc level4"><a href="bnawe.html#bnawf">Retrieving the Component Type</a></p>
<p class="toc level4"><a href="bnawe.html#bnawg">Setting Component Property Values</a></p>
<p class="toc level5"><a href="bnawe.html#bnawh">Getting the Attribute Values</a></p>
<p class="toc level5"><a href="bnawe.html#bnawi">Setting the Component Property Values</a></p>
<p class="toc level4 tocsp"><a href="bnawe.html#bnawl">Providing the Renderer Type</a></p>
<p class="toc level4"><a href="bnawe.html#bnawm">Releasing Resources</a></p>
<p class="toc level3 tocsp"><a href="bnawn.html">Defining the Custom Component Tag in a Tag Library Descriptor</a></p>
<p class="toc level3"><a href="bnaus.html">Creating a Custom Converter</a></p>
<p class="toc level3"><a href="bnaut.html">Implementing an Event Listener</a></p>
<p class="toc level4"><a href="bnaut.html#bnauu">Implementing Value-Change Listeners</a></p>
<p class="toc level4"><a href="bnaut.html#bnauv">Implementing Action Listeners</a></p>
<p class="toc level3 tocsp"><a href="bnauw.html">Creating a Custom Validator</a></p>
<p class="toc level4"><a href="bnauw.html#bnaux">Implementing the Validator Interface</a></p>
<p class="toc level4"><a href="bnauw.html#bnauy">Creating a Custom Tag</a></p>
<p class="toc level5"><a href="bnauw.html#bnauz">Writing the Tag Handler</a></p>
<p class="toc level5"><a href="bnauw.html#bnava">Writing the Tag Library Descriptor</a></p>
<p class="toc level3 tocsp"><a href="bnatt.html">Using Custom Objects</a></p>
<p class="toc level4"><a href="bnatt.html#bnatu">Using a Custom Converter</a></p>
<p class="toc level4"><a href="bnatt.html#bnatv">Using a Custom Validator</a></p>
<p class="toc level4"><a href="bnatt.html#bnatw">Using a Custom Component</a></p>
<p class="toc level3 tocsp"><a href="bnatg.html">Binding Component Values and Instances to External Data Sources</a></p>
<p class="toc level4"><a href="bnatg.html#bnati">Binding a Component Value to a Property</a></p>
<p class="toc level4"><a href="bnatg.html#bnatj">Binding a Component Value to an Implicit Object</a></p>
<p class="toc level4"><a href="bnatg.html#bnatl">Binding a Component Instance to a Bean Property</a></p>
<p class="toc level3 tocsp"><a href="bnatm.html">Binding Converters, Listeners, and Validators to Managed Bean Properties</a></p>
<p class="toc level2 tocsp"><a href="bnafd.html">15.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnaxu.html">16.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="gijti.html">17.&nbsp;&nbsp;Introduction to Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">18.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="giepu.html">19.&nbsp;&nbsp;Building RESTful Web Services with JAX-RS</a></p>
<p class="toc level2"><a href="gjjxe.html">20.&nbsp;&nbsp;Advanced JAX-RS Features</a></p>
<p class="toc level2"><a href="gkojl.html">21.&nbsp;&nbsp;Running the Advanced JAX-RS Example Application</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijsz.html">22.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijre.html">23.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="gijrb.html">24.&nbsp;&nbsp;Running the Enterprise Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">25.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level2"><a href="gkcqz.html">26.&nbsp;&nbsp;Using the Embedded Enterprise Bean Container</a></p>
<p class="toc level2"><a href="gkidz.html">27.&nbsp;&nbsp;Using Asynchronous Method Invocation in Session Beans</a></p>
<p class="toc level1 tocsp"><a href="gjbnr.html">Part&nbsp;V&nbsp;Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="giwhb.html">28.&nbsp;&nbsp;Introduction to Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="gjbls.html">29.&nbsp;&nbsp;Running the Basic Contexts and Dependency Injection Examples</a></p>
<p class="toc level2"><a href="gjehi.html">30.&nbsp;&nbsp;Contexts and Dependency Injection for the Java EE Platform: Advanced Topics</a></p>
<p class="toc level2"><a href="gkhre.html">31.&nbsp;&nbsp;Running the Advanced Contexts and Dependency Injection Examples</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;VI&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">32.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="gijst.html">33.&nbsp;&nbsp;Running the Persistence Examples</a></p>
<p class="toc level2"><a href="bnbtg.html">34.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level2"><a href="gjitv.html">35.&nbsp;&nbsp;Using the Criteria API to Create Queries</a></p>
<p class="toc level2"><a href="gkjiq.html">36.&nbsp;&nbsp;Creating and Using String-Based Criteria Queries</a></p>
<p class="toc level2"><a href="gkjjf.html">37.&nbsp;&nbsp;Controlling Concurrent Access to Entity Data with Locking</a></p>
<p class="toc level2"><a href="gkjia.html">38.&nbsp;&nbsp;Improving the Performance of Java Persistence API Applications By Setting a Second-Level Cache</a></p>
<p class="toc level1 tocsp"><a href="gijrp.html">Part&nbsp;VII&nbsp;Security</a></p>
<p class="toc level2"><a href="bnbwj.html">39.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bncas.html">40.&nbsp;&nbsp;Getting Started Securing Web Applications</a></p>
<p class="toc level2"><a href="bnbyk.html">41.&nbsp;&nbsp;Getting Started Securing Enterprise Applications</a></p>
<p class="toc level1 tocsp"><a href="gijue.html">Part&nbsp;VIII&nbsp;Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="gijto.html">42.&nbsp;&nbsp;Introduction to Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="bncih.html">43.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">44.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncdq.html">45.&nbsp;&nbsp;Java Message Service Concepts</a></p>
<p class="toc level2"><a href="bncgv.html">46.&nbsp;&nbsp;Java Message Service Examples</a></p>
<p class="toc level2"><a href="gkahp.html">47.&nbsp;&nbsp;Advanced Bean Validation Concepts and Examples</a></p>
<p class="toc level2"><a href="gkeed.html">48.&nbsp;&nbsp;Using Java EE Interceptors</a></p>
<p class="toc level1 tocsp"><a href="gkgjw.html">Part&nbsp;IX&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="gkaee.html">49.&nbsp;&nbsp;Duke's Tutoring Case Study Example</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td>
         <div class="header">
             <div class="banner">
                <table width="100%" border="0" cellpadding="5" cellspacing="0">
                   <tbody>
                      <tr>
                         <td valign="bottom"><p class="Banner">The Java EE 6 Tutorial
</p></td>
                         <td align="right"  valign="bottom"><img src="graphics/javalogo.png" alt="Java Coffee Cup logo"></td>
                      </tr>
                   </tbody>
                </table>
             </div>

             <div class="header-links">
	         <a href="./index.html">Home</a> | 
<a href="../information/download.html">Download</a> | 
<a href="./javaeetutorial6.pdf">PDF</a> | 
<a href="../information/faq.html">FAQ</a> | 
<a href="http://download.oracle.com/javaee/feedback.htm">Feedback</a>

             </div>
             <div class="navigation">
                 <a href="bnavt.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
                 <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
                 <a href="bnawa.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="bnavu"></a><h2>Creating Custom Component Classes</h2>
<a name="indexterm-892"></a><p>As explained in <a href="bnavh.html#bnavi">When to Use a Custom Component</a>, a component class defines the state and behavior of
a UI component. The state information includes the component&rsquo;s type, identifier, and local
value. The behavior defined by the component class includes the following:</p>


<ul><li><p><a name="indexterm-893"></a>Decoding (converting the request parameter to the component&rsquo;s local value)</p>

</li>
<li><p><a name="indexterm-894"></a>Encoding (converting the local value into the corresponding markup)</p>

</li>
<li><p>Saving the state of the component</p>

</li>
<li><p>Updating the bean value with the local value</p>

</li>
<li><p>Processing validation on the local value</p>

</li>
<li><p>Queueing events</p>

</li></ul>
<p><a name="indexterm-895"></a>The <tt>UIComponentBase</tt> class defines the default behavior of a component class. All the
classes representing the standard components extend from <tt>UIComponentBase</tt>. These classes add their own behavior
definitions, as your custom component class will do.</p>

<p><a name="indexterm-896"></a>Your custom component class must either extend <tt>UIComponentBase</tt> directly or extend a class representing
one of the standard components. These classes are located in the <tt>javax.faces.component</tt> package
and their names begin with <tt>UI</tt>.</p>

<p>If your custom component serves the same purpose as a standard component, you
should extend that standard component rather than directly extend <tt>UIComponentBase</tt>. For example,
suppose you want to create an editable menu component. It makes sense to
have this component extend <tt>UISelectOne</tt> rather than <tt>UIComponentBase</tt> because you can reuse the
behavior already defined in <tt>UISelectOne</tt>. The only new functionality you need to define
is to make the menu editable.</p>

<p>Whether you decide to have your component extend <tt>UIComponentBase</tt> or a standard
component, you might also want your component to implement one or more of
these behavioral interfaces:</p>


<ul><li><p><a name="indexterm-897"></a><tt>ActionSource</tt>: Indicates that the component can fire an <tt>ActionEvent</tt>.</p>

</li>
<li><p><a name="indexterm-898"></a><tt>ActionSource2</tt>: Extends <tt>ActionSource</tt> and allows component properties referencing methods that handle action events to use method expressions as defined by the unified EL. This class was introduced in JavaServer Faces Technology 1.2.</p>

</li>
<li><p><a name="indexterm-899"></a><tt>EditableValueHolder</tt>: Extends <tt>ValueHolder</tt> and specifies additional features for editable components, such as validation and emitting value-change events.</p>

</li>
<li><p><a name="indexterm-900"></a><tt>NamingContainer</tt>: Mandates that each component rooted at this component have a unique ID.</p>

</li>
<li><p><a name="indexterm-901"></a><tt>StateHolder</tt>: Denotes that a component has state that must be saved between requests.</p>

</li>
<li><p><a name="indexterm-902"></a><tt>ValueHolder</tt>: Indicates that the component maintains a local value as well as the option of accessing data in the model tier.</p>

</li></ul>
<p>If your component extends <tt>UIComponentBase</tt>, it automatically implements only <tt>StateHolder</tt>. Because all components directly
or indirectly extend <tt>UIComponentBase</tt>, they all implement <tt>StateHolder</tt>.</p>

<p>If your component extends one of the other standard components, it might also
implement other behavioral interfaces in addition to <tt>StateHolder</tt>. If your component extends
<tt>UICommand</tt>, it automatically implements <tt>ActionSource2</tt>. If your component extends <tt>UIOutput</tt> or one of the
component classes that extend <tt>UIOutput</tt>, it automatically implements <tt>ValueHolder</tt>. If your component extends
<tt>UIInput</tt>, it automatically implements <tt>EditableValueHolder</tt> and <tt>ValueHolder</tt>. See the JavaServer Faces API documentation
to find out what the other component classes implement.</p>

<p>You can also make your component explicitly implement a behavioral interface that it
doesn&rsquo;t already by virtue of extending a particular standard component. For example, if
you have a component that extends <tt>UIInput</tt> and you want it to fire
action events, you must make it explicitly implement <tt>ActionSource2</tt> because a <tt>UIInput</tt>
component doesn&rsquo;t automatically implement this interface.</p>



<a name="bnavv"></a><h3>Specifying the Component Family</h3>
<p>If your custom component class delegates rendering, it needs to override the <tt>getFamily</tt>
method of <tt>UIComponent</tt> to return the identifier of a <b>component family</b>, which is used to
refer to a component or set of components that can be rendered
by a renderer or set of renderers. The component family is used along
with the renderer type to look up renderers that can render the component:</p>

<pre>public String getFamily() {
    return ("Map");
}</pre><p>The component family identifier, <tt>Map</tt>, must match that defined by the <tt>component-family</tt> elements
included in the component and renderer configurations in the application configuration resource file. </p>



<a name="bnavw"></a><h3>Performing Encoding</h3>
<a name="indexterm-903"></a><p><a name="indexterm-904"></a>During the Render Response phase, the JavaServer Faces implementation processes the encoding methods of
all components and their associated renderers in the view. The encoding methods convert
the current local value of the component into the corresponding markup that represents
it in the response.</p>

<p><a name="indexterm-905"></a><a name="indexterm-906"></a><a name="indexterm-907"></a><a name="indexterm-908"></a>The <tt>UIComponentBase</tt> class defines a set of methods for rendering markup: <tt>encodeBegin</tt>, <tt>encodeChildren</tt>,
and <tt>encodeEnd</tt>. If the component has child components, you might need to use
more than one of these methods to render the component; otherwise, all rendering
should be done in <tt>encodeEnd</tt>. Alternatively, you can use the <tt>encodeALL</tt> method, which
encompasses all the methods.</p>

<p>Here is an example of the <tt>encodeBegin</tt> and <tt>encodeEnd</tt> methods:</p>

<pre>public void encodeBegin(FacesContext context,
     UIComponent component) throws IOException {
    if ((context == null)|| (component == null)){
        throw new NullPointerException();
    }
    MapComponent map = (MapComponent) component;
    ResponseWriter writer = context.getResponseWriter();
    writer.startElement("map", map);
    writer.writeAttribute("name", map.getId(),"id");
}
public void encodeEnd(FacesContext context) throws IOException {
    if ((context == null) || (component == null)){
        throw new NullPointerException();
    }
    MapComponent map = (MapComponent) component;
    ResponseWriter writer = context.getResponseWriter();
    writer.startElement("input", map);
    writer.writeAttribute("type", "hidden", null);
    writer.writeAttribute("name",
         getName(context,map), "clientId");(
    writer.endElement("input");
    writer.endElement("map");
}</pre><p><a name="indexterm-909"></a>The encoding methods accept a <tt>UIComponent</tt> argument and a <tt>FacesContext</tt> argument. The <tt>FacesContext</tt>
instance contains all the information associated with the current request. The <tt>UIComponent</tt> argument
is the component that needs to be rendered.</p>

<p>If you want your component to perform its own rendering but delegate to
a renderer if there is one, include the following lines in the
encoding method to check whether there is a renderer associated with this component.</p>

<pre>if (getRendererType() != null) {
    super.encodeEnd(context);
    return;
}</pre><p>If there is a renderer available, this method invokes the superclass&rsquo;s <tt>encodeEnd</tt>
method, which does the work of finding the renderer.</p>

<p>In some custom component classes that extend standard components, you might need to
implement other methods in addition to <tt>encodeEnd</tt>. For example, if you need to
retrieve the component&rsquo;s value from the request parameters, you must also implement the
<tt>decode</tt> method.</p>



<a name="bnavx"></a><h3>Performing Decoding</h3>
<a name="indexterm-910"></a><p><a name="indexterm-911"></a><a name="indexterm-912"></a>During the Apply Request Values phase, the JavaServer Faces implementation processes the <tt>decode</tt>
methods of all components in the tree. The <tt>decode</tt> method extracts a component&rsquo;s local
value from incoming request parameters and uses a <tt>Converter</tt> class to convert the
value to a type that is acceptable to the component class.</p>

<p><a name="indexterm-913"></a><a name="indexterm-914"></a>A custom component class or its renderer must implement the <tt>decode</tt> method
only if it must retrieve the local value or if it needs to
queue events. The component queues the event by calling <tt>queueEvent</tt>.</p>

<p>Here is an example of the <tt>decode</tt> method:</p>

<pre>public void decode(FacesContext context, UIComponent component) {
    if ((context == null) || (component == null)) {
        throw new NullPointerException();
    }
    MapComponent map = (MapComponent) component;
    String key = getName(context, map);
    String value = (String)context.getExternalContext().
        getRequestParameterMap().get(key);
    if (value != null)
         map.setCurrent(value);
    }
}</pre>

<a name="bnavy"></a><h3>Enabling Component Properties to Accept Expressions</h3>
<p><a name="indexterm-915"></a><a name="indexterm-916"></a>Nearly all the attributes of the standard JavaServer Faces tags can accept expressions,
whether they are value expressions or method expressions. It is recommended that you
also enable your component attributes to accept expressions because this is what page
authors expect, and it gives page authors much more flexibility when authoring their
pages.</p>

<p><a href="bnawe.html">Creating the Component Tag Handler</a> describes how a tag handler sets the component&rsquo;s values when processing the
tag. It does this by providing the following:</p>


<ul><li><p>A method for each attribute that takes either a <tt>ValueExpression</tt> or <tt>MethodExpression</tt> object depending on what kind of expression the attribute accepts.</p>

</li>
<li><p>A <tt>setProperties</tt> method that stores the <tt>ValueExpression</tt> or <tt>MethodExpression</tt> object for each component property so that the component class can retrieve the expression object later.</p>

</li></ul>
<p>To retrieve the expression objects that <tt>setProperties</tt> stored, the component class must implement
a method for each property that accesses the appropriate expression object, extracts the
value from it and returns the value.</p>

<p>If your component extends <tt>UICommand</tt>, the <tt>UICommand</tt> class already does the work
of getting the <tt>ValueExpression</tt> and <tt>MethodExpression</tt> instances associated with each of the attributes
that it supports.</p>

<p>However, if you have a custom component class that extends <tt>UIComponentBase</tt>, you
will need to implement the methods that get the <tt>ValueExpression</tt> and <tt>MethodExpression</tt>
instances associated with those attributes that are enabled to accept expressions. For example, you
could include a method that gets the <tt>ValueExpression</tt> instance for the <tt>immediate</tt> attribute:</p>

<pre>public boolean isImmediate() {
    if (this.immediateSet) {
        return (this.immediate);
    }
    ValueExpression ve = getValueExpression("immediate");
    if (ve != null) {
        Boolean value = (Boolean) ve.getValue(
            getFacesContext().getELContext());
        return (value.booleanValue());
    } else {
        return (this.immediate);
    }
}</pre><p>The properties corresponding to the component attributes that accept method expressions must accept
and return a <tt>MethodExpression</tt> object. For example, if the component extended <tt>UIComponentBase</tt> instead of
<tt>UICommand</tt>, it would need to provide an <tt>action</tt> property that returns and accepts
a <tt>MethodExpression</tt> object:</p>

<pre>public MethodExpression getAction() {
    return (this.action);
}
public void setAction(MethodExpression action) {
    this.action = action;
}</pre>

<a name="bnavz"></a><h3>Saving and Restoring State</h3>
<a name="indexterm-917"></a><p><a name="indexterm-918"></a><a name="indexterm-919"></a><a name="indexterm-920"></a>Because component classes implement <tt>StateHolder</tt>, they must implement the <tt>saveState(FacesContext)</tt> and <tt>restoreState(FacesContext, Object)</tt> methods to
help the JavaServer Faces implementation save and restore the state of components across
multiple requests.</p>

<p>To save a set of values, you must implement the <tt>saveState(FacesContext)</tt> method.
This method is called during the Render Response phase, during which the state
of the response is saved for processing on subsequent requests. Here is an
example:</p>

<pre>public Object saveState(FacesContext context) {
    Object values[] = new Object[2];
    values[0] = super.saveState(context);
    values[1] = current;
    return (values);
}</pre><p>This method initializes an array, which will hold the saved state. It next
saves all of the state associated with the component.</p>

<p><a name="indexterm-921"></a>A component that implements <tt>StateHolder</tt> must also provide an implementation for <tt>restoreState(FacesContext, Object)</tt>,
which restores the state of the component to that saved with the <tt>saveState(FacesContext)</tt>
method. The <tt>restoreState(FacesContext, Object)</tt> method is called during the restore view phase, during which
the JavaServer Faces implementation checks whether there is any state that was saved
during the last render response phase and needs to be restored in preparation
for the next postback. Here is an example of the <tt>restoreState(FacesContext, Object)</tt> method:</p>

<pre>public void restoreState(FacesContext context, Object state) {
    Object values[] = (Object[]) state;
    super.restoreState(context, values[0]);
    current = (String) values[1];
}</pre><p>This method takes a <tt>FacesContext</tt> and an <tt>Object</tt> instance, representing the array
that is holding the state for the component. This method sets the component&rsquo;s
properties to the values saved in the <tt>Object</tt> array.</p>

<p><a name="indexterm-922"></a>When you implement these methods in your component class, be sure to specify
in the deployment descriptor where you want the state to be saved: either
client or server. If state is saved on the client, the state of
the entire view is rendered to a hidden field on the page.</p>

<p>To specify where state is saved for a particular web application, you need
to set the <tt>javax.faces.STATE_SAVING_METHOD</tt> context parameter to either client or server in your
application&rsquo;s deployment descriptor.</p>


         </div>
         <div class="navigation">
             <a href="bnavt.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
             <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
             <a href="bnawa.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
         </div>

         <div class="copyright">
      	    <p>Copyright &copy; 2011, Oracle and/or its affiliates. All rights reserved. <a href="docinfo.html">Legal Notices</a></p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

